Skip to content

Docs refactoring

Kovitikus edited this page Sep 12, 2019 · 4 revisions

This is a whitepage for free discussion about the wiki docs and refactorings needed.

Note that this is not a forum. To keep things clean, each opinion text should ideally present a clear argument or lay out a suggestion. Asking for clarification and any side-discussions should be held in chat or forum.

Griatch (Aug 13, 2019)

This is how to make a discussion entry for the whitepage. Use any markdown formatting you need. Also remember to copy your work to the clipboard before saving the page since if someone else edited the page since you started, you'll have to reload and write again.

Kovitikus (Sept. 11, 2019)

Batch Code should have a link in the developer area. It is currently only listed in the tutorials section as an afterthought to a tutorial title.


In regards to the general structure of each wiki page: I'd like to see a table of contents at the top of each one, so that it can be quickly navigated and is immediately apparent what sections are covered on the page. Similar to the current Getting Started page.


The structuring of the page should also include a quick reference cheatsheet for certain aspects. Such as Tags including a quick reference section at the top that lists an example of every available method you can use in a clear and consistent format, along with a comment. Readers shouldn't have to decipher the article to gather such basic information and it should instead be available at first glance.

Example of a quick reference:

Tags

# Add a tag.
obj.tags.add("label")

# Remove a tag.
obj.tags.remove("label")

# Remove all tags.
obj.tags.clear()

# Search for a tag. Evennia must be imported first.
store_result = evennia.search_tag("label")

# Return a list of all tags.
obj.tags.all()  

Aliases

# Add an alias.
obj.aliases.add("label")

ETC...

In regards to comment structure, I often find that smushing together lines with comments to be too obscure. White space should be used to clearly delineate what information the comment is for. I understand that the current format is that a comment references whatever is below it, but newbies may not know that until they realize it.

Example of poor formatting:

#comment
command/code
#comment
command/code

Example of good formatting:

# Comment.
command/code

# Comment.
command/code
Clone this wiki locally
You can’t perform that action at this time.