search

occam-ra / occam

OCCAM Reconstructability Analysis Tools
Other
20 stars 14 forks source link

Convert existing user manual to markdown and post #33

Closed gdcutting closed 5 years ago

gdcutting commented 5 years ago

The existing user manual is a valuable resource and is up-to-date with the current version of OCCAM. Let's convert to markdown and post to the repo wiki.

gdcutting commented 5 years ago

Initial markdown conversion of existing user manual: https://github.com/gdcutting/occam/blob/master/doc/occam-user-manual.md

Used pandocs to convert existing OCCAM user manual from docx to markdown. It mostly did a pretty good job, though it definitely needs some touch-up. Once the document structure is properly set in markdown, we can replace the TOC at the top with one automatically generated from the document structure.

gdcutting commented 5 years ago

User manual needs a bit of work:

gdcutting commented 5 years ago

This is mostly completed. Should I split into sections (a file/page for each one) for the wiki?

gdcutting commented 5 years ago

Part of me wants to slightly reorganize the content. Some of the main sections are many pages, and some of them (like VIII, IX, and X) are only a couple of sentences, so the distribution is unbalanced.

gdcutting commented 5 years ago

Was conflicted about where docs should live but then Joe pointed out to just let them live in docs/ at main repo and just link to that GitHub page from the .io site somewhere (don't need the whole giant manual at the .io page, just a link to the GitHub page and/or wiki). In fact, can link to doc/ at main repo from Getting Started page (which I need to link from .io front).

Still thinking through the degree of separation that's appropriate between the markdown user manual and the (not-yet-existent) wiki.

Need to clarify directory structure (mainly where images/ lives) and then will do pull request to merge new docs material (user manual and design recommendations) upstream.

Also need a little more cleanup to emphasis at under XIV and forward.

venkatachalapathy commented 5 years ago

Thanks for initiating this, @gdcutting .

My feeling is that since we are anyway moving away from the web hosted version into a package, we need not spend too much time thinking about this. A bare minimum version somewhere should suffice for now. In any case, I am not sure if any one actually used this user manual and what their experience is while using the existing pdf.

Since @joefusion is teaching DMIT, we might be able to get some feedback from the current class on what the manual gets right; where it misses the mark; and where it is outright confusing.

venkatachalapathy commented 5 years ago

User manual needs a bit of work:

I'll try to be helpful here. Let me know how I can help.

gdcutting commented 5 years ago

I'm very close to being done. I am with you - don't want to spend too much time. But it was worth putting a few hours into getting a markdown version up. Am about to (sometime tonight) do a pull request to bring in this doc stuff I've been working on. High priority right now is getting some working design proposal docs finished before next meeting. Don't have anything like a full plan for structural changes but want to start having a design discussion and be organized about the approach. Right now I'm just trying to get into print a bunch of stuff that I have learned in spending weeks with the code now. Watch for changes in the next day or two.

gdcutting commented 5 years ago

I think I've decided to use (or at least try out) this: https://readthedocs.org/

The user manual isn't that important; it will become obsolete soon anyway. What is very important is getting some working planning documents up and running, which I have made progress on but am still in process. That will be an ongoing thing for a few weeks at least but I want to get some working recommendations in place by next meeting. Pull request soon.

gdcutting commented 5 years ago

Docs published at https://occam-ra.readthedocs.io. Default appearance is bad but I will fix that up.

gdcutting commented 5 years ago

I consider this closed. The manual is converted to markdown, posted to the repo, and hooked to the readthedocs page. User manual probably still could use some minor formatting, but it's really not worth spending any more time on that right now. It will become obsolete very soon anyway. Wiki is a separate issue, I will open that.