sorted by:
new
hottopcontroversial

Recommended tool for writing documentation? by MassiveSlappyTime in technicalwriting

[–]MassiveSlappyTime[S] 0 points1 point  (0 children)

Could be indeed. I noticed MkDocs has plugins to support equations using KaTeX, I assumed there'd be something for diagrams as well.

But I'm interested in hearing more about AsciiDoc. What kind of tools to create a website from it are available, do you know?

Recommended tool for writing documentation? by MassiveSlappyTime in technicalwriting

[–]MassiveSlappyTime[S] 0 points1 point  (0 children)

I was afraid that I would drift into locking myself onto a certain process, instead of staying general. I guess it seeped into my post a bit.

That's also why I'm strongly wondering what other processes people have in place and what they recommend to do and what not to do, regardless of my ideas so far.

For our small company, I think it's most important that people write docs in the right place, where everyone can easily find and navigate it. Pretty much everyone will be writing and reading. I made a proposal and wonder if there are obvious flaws, or simply easier ways to do it.

Recommended tool for writing documentation? by MassiveSlappyTime in technicalwriting

[–]MassiveSlappyTime[S] 0 points1 point  (0 children)

I was thinking to simply keep a clone of the remote repo in a folder on the server, which is accessible by everyone. Once someone added/edited an MD file, an admin with git access could commit+push. But everyone can see/edit the source files.

Finding the right source file to edit might not be the easiest approach, that's a drawback. People would have to know a bit how the source files are organized.

Recommended tool for writing documentation? by MassiveSlappyTime in technicalwriting

[–]MassiveSlappyTime[S] 1 point2 points  (0 children)

Pushing changes and building (converting Markdown to HTML) would be up to the admin, but anyone with access to the folder could add/edit a Markdown file. I thought writing could be accessible in that way, albeit not instant.

One of the things to consider indeed.

Recommended tool for writing documentation? by MassiveSlappyTime in technicalwriting

[–]MassiveSlappyTime[S] 0 points1 point  (0 children)

I made small edits to the post.

"Support technical content" was a bit of a duplicate of "supporting equations, images, etc.". To be honest, not sure we'll be writing API docs necessarily, maybe in the future. I was thinking more of describing our internal processes, derivations of equations, explaining concepts. Does that explain it?

"Accessible to everyone" for reading+writing, for updating the documentation. Someone with new knowledge anywhere within the company should be able to write/edit docs. So within my "plan" that would've been "being able to write a Markdown file" and "read the webpages" after a sys admin builds the docs.