search

jacquetc / plume-creator-legacy

Fork of the first Plume Creator repository from SourceForge. Written in C++ / Qt5
Other
0 stars 0 forks source link

Discuss tools, formats for documentation #13

Closed ParaplegicRacehorse closed 4 years ago

ParaplegicRacehorse commented 8 years ago

A start on the documentation has been made with pull request jacquetc/skribisto#6

@jacquetc, I looked through some of the code and ... I can't follow it well enough to write much in the way of a user manual. While I can document obvious features and how to get around the UI, any hidden technical gems, like keyboard shortcuts or command line arguments would get left out of the manual. As you continue to edit the source, would you place comments to help in this regard? Preferably something like NaturalDocs or Asciidoclet. Having easy access to at least the technical documentation would help tremendously in writing a user manual. Also, code comments are good! :+1:

And... you're probably going to have to be the guy who writes the plugin-authoring manual.

Potential documentation helpers: It looks like using Plume to write the manual or even technical documents is not likely to work, at least not if it is to be easily handled by git and diff. I propose writing in Asciidoc or Markdown. Comments?

ParaplegicRacehorse commented 8 years ago

A beginning TODO has been place in a gist. https://gist.github.com/ParaplegicRacehorse/316f67d91124e95092a68340e2b6ac24

jacquetc commented 8 years ago

@ParaplegicRacehorse I am trying to write comments in the main classes. I'm using reStructuredText with Sphynx http://docs.python-guide.org/en/latest/writing/documentation/

ParaplegicRacehorse commented 8 years ago

Okay. Clearly I haven't found the main classes, yet. :frowning: Granted, I haven't yet done a whole lot of digging. Is the output from Sphynx being auto-built?

Geez. I guess I really should just go dig through the src/ and see what I see.

ParaplegicRacehorse commented 8 years ago

Okay, I was wrong. Now I know what to look for, I found all the documentation comments in src. There's just nothing there in plain language for me to use. I assume that last sentence should be followed with a ,yet?

jimmysjolund commented 8 years ago

I would prefer Markdown, but that's mainly because I already know the syntax.

ParaplegicRacehorse commented 8 years ago

I'm okay with Markdown. I already know the syntax so there would be pretty much no learning curve. There are also a whole lot of really friendly live-preview editors or extensions for editors. This is not true of Asciidoc, or RST for that matter. It's also dead-simple to learn for any potential contributors. And pandoc works well with it.

The advantage of Asciidoctor is a wider variety of available output formats, without need to pass through something like pandoc and a bunch of other fun stuff like includes, variables, diagrams, UML, mathjax, and programmatic compilation with other tools like Gradle. The syntax is equally simple, but a little different from Markdown. It should be quick to learn.