Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. It either explains how it operates or how to use it, and may mean different things to people in different roles. Documentation is an important part of software engineering. https://en.wikipedia.org/wiki/Software_documentation
Stage 0 — Google docs plus keeping functionality in my head
It’s easy when you have only one person that coding your project.Main problem — every time that I want to write something new:a) I should open my Gmail b) then go to Google Docsc) then I should pick the folder where I save all data, d) open my document
Disadvantage
- It’s a bit unmanageable.
- If you want to share a link with someone — you should generate a sharable link, copy and send it.
- Some people don’t have a google account(crazy right?). And it can be a problem too.
- Content didn’t index by web spiders so nobody can find it accidentally.
- Doesn’t have a cool search(at least I use it mostly for title search only)
- When you work on a big document you need to create a table of contents yourself.
Link: https://www.google.com/docs/about/
GitHub
Stage 1
I keep my code and documents/files at main GitHub repositories.
DisadvantageA lot of mess because it’s for storing your code. Sometimes having everything in one place are very pressing.Hard to search. You need to remember where you keep it.
Link: https://github.com/
Stage 2
Instead of having a development plan at markdown files — I move some tasks to GitHub issues, add labels and milestones.
It is a good approach if you still working alone.But when a project will grow — you’ll drown. As I did. I have a big long list of issues. it’s hard to manage it quickly.But it’s better to have a documented issue on Github, instead of storing it in memory or papers.
Stage 3I create a few separated repositories for documentation only.As I was still alone — I just moved all files without any structure.
DisadvantageIt’s still doesn’t look like proper documentation. Nobody can navigate it, I store content in different languages, etc.
Stage 4
Github has a good tool for documentation — pages/wikis.It’s a good idea, but it didn’t work well for me. Not sure why. Maybe it requires a lot of time for sharing and storing data there. I think it can work for many people. Wikis didn’t require a lot of tech knowledge to start working with.
DisadvantageHard to upload images/screenshots. But! it was an opportunity for us.I create separated repositories for keeping all assets in one place.So logos, brand book, database schemas stored at “creative” repository.It’s also good way to share information with designers. And I make it more easy to navigate for humans. And when I needed to share something — I just go to that repository and copy an URL.
Link: https://pages.github.com/
Stage 5 — Gitbook
Really cool product. I like it. It syncs with Github.And it looks good. Works fine with Markdown formatting.
Disadvantage
- It has some UI issues. Like it has a custom online editor aka draft.js
- And it’s not very intuitive how to add cross-links to subpages. You need to make a 2–3 moves if you want to do it. Again it looks good and has more features that I didn’t explore, like slack integration
It’s better to separate data between different scopes(sections of documentation). Because if you’ll have 3 main pages with 10 subpages each — it will be hard to navigate or drag pages between sections. For the not-coding person, it’s definitely a good way to go.
Why I leave it? They finish their beta testing and introduce their paid plans, and we cannot afford them right now.So it was time for new moves.
Link: https://www.gitbook.com/
At some point, between stage 3–4 I read about Amazon development approach.Briefly — you explain in simple sentences what release will have in a result.And I recommend you to read more about it. Link: https://www.quora.com/What-is-Amazons-approach-to-product-development-and-product-management
Current stage
This is not a linear process, so we still stuck with some documentation at previous stages. Right now we moving everything to Docusaurus.
I like that it’s a tool baked by Facebook. It’s free and open-sourced.It builds with React so we can adjust the code if it is necessary.Similar to Gitbook — works with Markdown. But it’s more for coders.Or developer should set it up and the manager will just work with content.With markdown format, you can read/view files at Github too.It also works great with GitHub pages. You just need to deploy it on gh-pagesAnd you’ll have a separated URL with SEO stuff that can drive more attention to our project.
Links:
Summary
Documentation is a very important tool in the development process and you should use it as much as possible.If you have long meetings, 1-to-1 conversations, kilometers of chats in Slack — then you need to improve it ASAP.
I still don’t feel like this is the end of our “evolution process”. A major goal will be to increase modularity and drive more attention to it. We still use it only if it necessary. Instead of “update a documentation file -> share data with team members” we are “having long conversations and then copy some of our comments into documentation for the future needs”.
If you want to know about how I manage my projects — read it here: https://medium.com/quick-code/how-i-manage-my-projects-c17c78c796c4
Clap if you like it (Or I will delete your facebook account)