[oi-dev] demonstration docs website

[Aurélien Larcher]

> 1) Place documentation under distributed version control.
>
> Not all documentation I think should be under version control.
> Though, documentation created by the people that help create OI I
> think would.  I really think that what you are creating is not a
> documentation site but a new handbook.  Is there a public, updatable,
> handbook right now?
>
> I would keep the wiki AND have this nice handbook.  I really think the
> front facing page should be integrated somewhere branching off of the
> main site to summarize the entirety of the OI documentation structure.
>
> It seems like, with the wiki and handbook approach, you would be
> duplicating work but then lets take a look at this page:
>
> http://wiki.openindiana.org/pages/viewpage.action?pageId=4883847
>
> That page needs updated, it looks like 4k problem has been fixed, or
> possibly not.  Why are people commenting instead of fixing the wiki
> itself?
>

But I think with this example you are exactly pointing out the fact that
documentation covers different things:
- developer notes
- ephemeral information (i.e workarounds)
- end user documentation (fairly static)
- etc...

So Wiki and Michael's proposal are complementary as they address different
types of documentation and it was never the question to replace the Wiki.
The Wiki does not allow you to generate to different media as it would be
required for the Handbook.


>
> If you have a handbook that developers can edit simply and quickly
> once a problem has been fixed in OI, is this not better?  Or is this a
> problem solved by man pages?
>
> 2) Lower the bar of entry to the documentation process.
> I do not know why the bar is high right now?  Can you explain this
> more?  Making an account on the wiki is not hard.
> Making an account on git is not hard either but I would like to
> mention that most people are used to editing wikis.
>

Ability to ask for review comes to my mind.


>
> 3) Make changes and quickly deploy those changes in some kind of
> automated fashion (e.g. continuous integration).
> Once again, I already talked about developer -> git docs editing, but
> can you please explain this more?  Wikis are just click and edit.
>
> 4) Present the documentation in an organized and aesthetically pleasing
> way.
>
>  https://makruger.github.io/website/pages/docs/handbook.html does not
> work.  https is broken in your css.
>
> I agree a bit on this.  I do not like Confluence, but it does make for
> a nice looking index layout.  I am really a fan of mediawiki and I do
> not understand why they chose to go with the Atlassian Confluence
> Community License when mediawiki is FOSS.  To each there own and I am
> sure it was thought about.
>
> I like straightforward layouts that do not obfuscate things.  I want
> all the information on one page....not a million different menus.  One
> large TOC/index and all the text at my fingertips.  i should not need
> a search engine to search a manual.  If I open up a handbook, I want
> the handbook.
>
> Though, if what you have created were to be accepted, you are adding
> more work.  I do not OI has a dev lead or team right now right?  Who
> is going to support it?  The support/work might not be in vain though
> because documentation should support the release.  It is very
> frustrating for users to use an OS and not find the docs they need.
> Or find out dated docs.  Do you think a developer would take time to
> fix docs though when they already have man pages and README's?
>

I would actually be more confortable editing source files and doing PRs.
In a math/physics research environment everything is written in LaTeX (also
mark-up language for  algo/code-related documents).
Even applications for fundings are shared in git and merged from different
branches.


> If you were to link the docs via github to code changes, every release
> could have its handbook frozen in time/git releases/names for each
> release.  In fact I think this could be a powerful feature if OI ever
> does an LTS release.
>

I think so too.


>
> _______________________________________________
> oi-dev mailing list
> oi-dev at openindiana.org
> http://openindiana.org/mailman/listinfo/oi-dev
>



-- 
---
Praise the Caffeine embeddings
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://openindiana.org/pipermail/oi-dev/attachments/20160506/1cbbb167/attachment-0005.html>