Any tips for writing product documentation? Soon going to release open-source project and I want to make it user-friendly with an accessible documentation. Never done it before (besides small features at work), even worse my writing skills suck, but I guess that’s my personal problem to figure out. Now one of the goals is to make docs well organized and easily maintainable if something changes. Had way too many encounters with outdated docs, so at least want to get mine right. Curious to hear positive/negative experiences of others.

  • 1
    I suggest you look at microsoft docs for c#, or the docker docs, or the unity tutorial docs. I think these are nicely structured and progress smoothly in taking a user from 0 to X.
  • 1
    Document what each feature does. Stick to the principle of the least surprise - but clearly document gotchas where they are unavoidable.

    Supply a demo project where stuff can be seen in action. The jump from a feature list to "how do I use that stuff for real" is often huge - especially if the UI is misdesigned (looking at you, Git).

    For the tech docs, the number 1 thing that most OSS projects are missing is some sort of architectural overview. Some top level diagrams how things go together.
  • 1
    Vuepress is quite nice documentation system. It's markdown based and you can use mermaid diagrams. Plus you can add webm or gifs to explain stuff.

    VuePress tutorial
  • 2
    So there are several things questions I think your docs should answer:
    What does the project do?
    What problem does it solve?
    How do try it out?
    How do install it in production?

    Docs for functions:
    Use common names for things, ( think about how people search docs usong ctrl+ f , so what keywords would they use? Authentication, authorization, login etc should all be linked to the same place ( if they are indeed the same)
    Make sure the docs mention them.
    Think about at least three ways people browse your docs: searching for the correct arguments for a function, how to install the project and "I've got an issue and I don't know what's wrong or how to fix it.
  • 1
    @hatemyjob @Fast-Nop @heyheni @Charmgoggles thank you guys for tips, hope to make use of them.

    Anyway, that wasn’t exactly what I was asking. My concern is to keep docs up to date if sth in code changes, for example, I change configuration option from ‘title’ to ‘name’, how do I make sure I don’t forget to update option also in docs?
  • 0
    I use tools that keep the documentation next to the code. Some of the tools also warn if the arguments differ from the code. In pycharm this works really well.
    But for the readme that doesn't work, unless you compile the readme with the actual code.
Add Comment