DEV Community

Leonardo Teteo
Leonardo Teteo

Posted on

What is a good documentation for you and what tools do you use?

It seems documentation never gets the love its deserve for our own good and there are many tools for that, although I'm still looking for the right one.

What are the ones that make part of you guys pipelines?

Top comments (18)

Collapse
 
sunk818 profile image
sunk818 • Edited

Personally, I like using GitLab's Wiki feature. FREE. I tried GitHub Wiki but their wiki only allows you to link images. GitLab wiki actually let's paste images from the clipboard. I don't know about you, but much of my documentation have screenshots.

Publii is static content publisher which you could use as documentation and also makes including images easily. Hooks into GitHub pages (or just export as static set of files).

Other options:

GitBook
WordPress w/ some add-ons (paste image from clipboard)
Confluence by Atlassian

Collapse
 
leoat12 profile image
Leonardo Teteo

Confluence is the one we at my company are using right now, but I don't know, I personally thinks that the documentation has to be along with the code to avoid people not updating them. When it is not there in the IDE devs will hardly remember them. I don't.

Collapse
 
sunk818 profile image
sunk818

Code comments is an entirely differently discussion as is readable code. While I agree with your point, I rarely meet devs that like to document. They are called technical writers for a reason and not devs.

Thread Thread
 
leoat12 profile image
Leonardo Teteo

I didn't mean that the docummentation should be comments in code, it would be in the same repository, like markdown or asciidoc files, that would be written while in development and then built along with the code to a convenient format. It is unfortuante because there is no better person to know what they meant by the code than developers.

Thread Thread
 
sunk818 profile image
sunk818

Do you have an example of this where someone writes separate documentation alongside their code? What purpose would it serve and who is the audience that would need to read it? If a dev is writing for another dev, documentation in the repo works great. If the audience is non-technical, I'd question if that's the best way to communicate documentation. I work at a non-profit and I'm constantly in meetings "translating" between the developer and project sponsor.

Markdown is natively supported in GitHub, so I'd prefer it... but for more complex documents, AsciiDoc looks cool with an online converter like gist.asciidoctor.org/ :)

Thread Thread
 
leoat12 profile image
Leonardo Teteo

The documentation would be made along the repository, but it would be available on a website, if any person wanted to read it, that's what I envision. AsciiDoc is also supported by Github and along with Asciidoctor you can convert it to HTML with a great layout and make it available where it is convenient. It would be for mostly techinical people, developers and IT support personel.

Collapse
 
princebillygk profile image
Prince Billy Graham Karmoker • Edited

What about imgbb with GitHub wiki?

Collapse
 
sunk818 profile image
sunk818

Do you mean imgbb? Again, you have to upload images separately and the workflow is separate. I don't know why GitHub wiki doesn't include image inline attachment like they allow in GitHub issues.

Collapse
 
cjbrooks12 profile image
Casey Brooks

I've been building Orchid to be a great option for building and publishing documentation sites, bringing together all your wikis, blogs, and code docs into one tool.

orchid.run/

Collapse
 
erikpischel profile image
Erik Pischel

I'm going to start with asciidoc. Some colleagues have used it before so there's help available. Put it in a git repo and maybe a build pipeline to automagically generate pdf or so.

Personally I use Emacs org mode which has its own nice markup language (supported by pandoc) but here you go

Collapse
 
leoat12 profile image
Leonardo Teteo

Asciidoc, along with Asciidcotor, is one I've been taking a look at, it feels great, just needs a good pipeline to introduced into CI/CD of the projetcs.

Collapse
 
gregfullard profile image
Greg Fullard

For the last few years I've been standardising on Sphinx for all documentation. This includes all docs, even requirements etc. We store the Sphinx folder in the repo whick ensures the app will never get detached from it's docs.

Collapse
 
mathewthe2 profile image
Mathew Chan • Edited

I recently found MKDocs and it looks pretty nice with the material theme. I love that it's got an inbuilt search functionality.

Collapse
 
rinzler profile image
Rinzler • Edited

Here, we write our docs in markdown and host on Github repositories, as for the writing tool, we use stackedit.io/, it's incredibly simple and effective =)

Collapse
 
thealphamerc profile image
Sonu Sharma πŸ’™

Few days back I found Gitbook and it is really good for documentation.
You can check it at gitbook.com/

Collapse
 
rowland007 profile image
Randy

What tools have you used?

So far I have only used Mkdocs and it has been simple to configure, quick to publish, and compatible with Github Pages or Read the Docs.

Collapse
 
pucherico profile image
Jose A. Puche

Now I'm using just the same IDE for coding: VS Code. Documenting in Markdown and versioning in Git (e.g GitHub repo or gists).

Collapse
 
gcnu profile image
seenu

Was using gitbook for years but after their price changes, i wanted to have something opensource, after spending months trying many, i ended up with vuepress and i just love it.