Writing design docs

Users
#1

There will be more and more features and they will interact with one another. As the internals get more complicated, I feel it is good to have design docs for various components and keep updating these docs.

Discourse is great for discussion, but it doesn’t seem like the best place to hold details about internal workings which can evolve over time. Wiki is good too, but it feels more cumbersome compared to just typing into GoogleDocs. You can also put nice figures inside.

For example, I was modifying query_test and found that GetIterator and iteration doesn’t seem to work. It seems that I need to do some merging of the gotomic maps with RocksDB.

What do you all think about using GoogleDocs more?

#2

Wiki can take images. In fact, we have one in Beginners Guide. Also, Wikipedia has tons of images.

There’re many advantages of wiki over Google docs:

  • The usage of screen real estate. Wiki does a much better job than the narrow viewing area forced by Google or Github or other modern solutions. IMHO, wiki reads much better – in fact, that was the main reason I chose wiki over other solutions.
  • Wiki Templates: Docs do go out of shape or are incomplete, or need further improvement, etc. Wiki has a range of templates that can be easily added to reflect those things. Having this in the face of both users and editors helps keep things up to date.
  • Wiki notes, tips, warning etc.: Sort of like helpers to templates, they’re a great way to indicate something important and grab the attention of the user.
  • Universal edits: Anyone can update the wiki, and it’s designed to be editable by everyone. You can see a list of changes and can approve or deny those. Having wiki enables our users to modify the documentation to fix errors or clarify sentences.
  • Section editing: Wiki has this amazing feature by which you can modify only a certain section. From afar, this seems like a small optimization, but as your documentation starts to grow, it becomes a very handy tool allowing you to focus on just one thing and improve it.
  • View mode and edit mode: Again helps a lot with being comfortable with the documentation. When reading, you can be sure that no extra keystroke will cause the document to change accidentally. It’s a simple and very useful feature (also Vim operates this way).

Overall, I think Wiki is designed around documentation. Some of the best documentations have been built on Wikis:
https://wiki.archlinux.org/
https://wiki.gentoo.org/wiki/Main_Page

OTOH, Google Docs is built as a replacement for Microsoft Word – which is exactly what it does best. I haven’t had a great experience with building world-class documentation with Google Docs.

I’d advise spending some time with the Wiki formatting. It’s very similar to markdown, so you’ll get used to it really fast. The other advantage that Google Docs provides is WYSIWYG editor. I’ve played with that for wiki, but those tend to slow you down instead of speed you up. A simple text editor can do a much better job helping you put your thoughts down – I used Vim to write all of the Wiki documentation.

#3

Thanks for the comprehensive reply. In that case, we should all write a bit more wiki. Nobody likes writing documentation, but when I waste a few hours figuring something basic that could have been documented, I feel maybe we should write a bit more. Maybe each big component can have a wiki page which documents how it works roughly. (I don’t exactly like making this so public… but not sure)

2 Likes
#4

Absolutely – we should all be writing more documentation in wiki. Also, feel free to file bugs against me or other people who have authored certain components and would be the right people to write documentation. But, also, as you pick up things, make it a point to update the wiki, even though you haven’t written that piece of code. The policy in place is, leave it cleaner than when you began.

That’s alright! Our entire code base is public, so are our salaries and so is most of our interaction including this one. We chose wiki for that same purpose, to keep things public.

1 Like
#5

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.