Should include documentation in this repository.

[Former user]

Updated (by Aaron)

Migrate developerWorks iToolkit API docs to this repo in /docs/README.md.

Original

Consists of two parts: 1) Move from its current home at http://youngiprofessionals.com/wiki/index.php/XMLSERVICE/Python 2) Include better documentation of the itoolkit-lite package and how to get it.

[Aaron Bartell]

Couple things:

• Please reveal who is making this request (I've subsequently changed the Issue tracker to only allow authenticated users)

• This is the Node.js iToolkit repo, not the Python iToolkit repo (you pointed at the YiP Python page). To my knowledge the current formal Node.js iToolkit documentation is on developerWorks. Btw, I agree it should be migrated to here and then update developerWorks to point to here.

• What is the "itoolkit-lite" package? The only reference I could find was relative to Python.

• Are you willing to volunteer to help with the documentation migration from developerWorks to this repo?

On final note, we need to determine what documentation should look like in all the various IBM i OSS repos. I vote we do a single-page markdown file and go from there. Bigger projects (i.e. hapijs) have entire sites dedicated to documentation. I don't believe most packages need that and instead docs can be facilitated in one of the following locations:

• README.md
• docs/README.md

For this repo I vote we use the top-level README.md for installation and common usage examples, and then have a link pointing at docs/README.md to see all of the content that will be migrated from developerWorks. This can be our starting point and we can change it in the future if necessary.

@ThePrez, @mengxumx, @rangercairns, and @kadler, do you have preferences for how we do docs for the various IBMiOSS projects on Bitbucket? See my initial recommendation above.

[Jesse G]

Wow, I messed this up (sorry, still jetlagged from travel, perhaps). I not only forgot to log in (a common mistake I make on bitbucket), I opened the issue to the wrong dang place.

In any event, I am in favor of your proposal for how to lay out the documentation.

developerWorks and/or yips can link to the documentation in the various repos. I have mixed emotions about this in general, because we will get "documentation sprawl" as opposed to one or two places (dW+YiPS) having all the information. But, I think it's best to align the doc with the source code locations. It also becomes community-improvable when on bitbucket/github/etc.

Since this particular issue was related to Python, should we close this one, move it to the correct repo, or continue this discussion here?

[Former user]

Anyway, an opinion ... Reference litmis/python-itoolkit case study. Python project includes directory toolkit/doc. Nobody ever finds or reads toolkit/doc. My vote, python toolkit/doc was a failed idea (my opinion). Therefore, I have doubts including a project/docs works any better. Aka, stay with current many locations for 'doc' pattern. Perhaps what people are really after is working samples to cut/paste, litmis already has some of these for node (i recall).

[Former user]

Also (not a git expert), but anything 'changing' ends up under a commit 'key' (7d7131ed7462fe707ff04fe1406ead4a68a2ee76/docs), therefore you have to navigate through 'Source' link to get to documentation. Again, my experience with python toolkit/doc is nobody uses the 'Source' link hunt and peck useful.

[Aaron Bartell]

Since this particular issue was related to Python, should we close this one, move it to the correct repo, or continue this discussion here?

We have an existing issue in Python iToolkit that addresses this need. This repo has the same dilemma so we should keep this open. Leaving it open will also allow us to point volunteers at the Issue.

Nobody ever finds or reads toolkit/doc.

My perception is that the docs/ directory doesn't get used because you have to stumble upon it; it isn't referenced in the root README.md and it also isn't a root-level directory (I believe it should be at the root). Instead the README.md points users to YiPs.

I did some Python iToolkit work for a customer and even though I am fairly "connected" to IBMiOSS I was struggling to understand where the authoritative Python iToolkit docs resided.

[Aaron Bartell]

therefore you have to navigate through 'Source' link to get to documentation

I've updated the READEME.md page so the itoolkit/docs directory is more visible.

Special Note:

To reference a specific version of a file you can simply copy and paste from the browser, like so:

https://bitbucket.org/litmis/python-itoolkit/src/2adc2c18fcc988d4ac71828f3d05ee4bc3b32485/itoolkit/doc/?at=master

To reference the most current version of a file (right now and in the future) you can remove the commit SHA-1 and replace it with the branch name (i.e. master)...

https://bitbucket.org/litmis/python-itoolkit/src/master/itoolkit/doc

[Former user]

https://bitbucket.org/litmis/python-itoolkit/src/master/itoolkit/doc

Ok (did not know). Yes. A 'latest' pointer from main page to /docs would have a better chance of 'find me'.

... authoritative Python iToolkit docs resided.

Could that get any more loaded with politics? Ok. I can live with /docs as 'official' documentation usually 'reference' material for 'experts' (litmis/python-itoolkit/src/master/itoolkit/doc). Ok, boring, the syntax facts.

Mostly, I am a google fan, here a sample, there a sample, everywhere a sample, is better for greater majority of people. Whole idea google search is many, many sites form many contributes ("open" by definition). So no, I really don't like idea of 'hog tying' documentation to one site/project for all of IBM i.

[Aaron Bartell]

@rangercairns

I think we're on the same page. I am not purporting to discontinue examples/samples on other sites, only that there is one place the world can go to to get the "boring syntax facts" (something that had me pulling my hair out a bit in a recent Python customer engagement).

I will take a first stab at migrating the Node.js iTooltoolkit docs from developerWorks to this repo. Then we can step back and see what works and what doesn't.

[Aaron Bartell]

@ThePrez (or @rangercairns or @kadler), could you get me the raw markdown from the current Node.js iToolkit docs? Will be easier to use that as a starting point.

[Former user]

So one more BIG no ... aka ... /docs idea is a big mistake ...

I have never seen google come up with a link to a git project subdir/README.md. I believe the reason is the SHA-1 key prevents anything from staying 'google relevant' in terms of popular counting (but this is only a guess). I think you will simply remove IBM i documentation from the world view if you pursue this /docs idea.

Ok, now my "open" politics is in the "open". This is not a good idea. WE should never fight google search, we will lose (big time).

[Aaron Bartell]

Ok, now my "open" politics is in the "open".

Open is better.

I am curious what you're searching for and not finding. When I search for open source project documentation it is usually the Github/Bitbucket repo that shows up in the top 5 organic search entries (coupled with oodles of StackOverflow entries).

I see well-organized OSS projects documented in three primary fashions:

• Big project: separate website. Ex: https://hapijs.com/api
• Medium project: some docs on root README.md though further pointing to internal .md file for more docs. Ex: Hoek points at API.md
• Small project: Everything in root README.md with comments that usually say something like "More questions? Read the code or create an Issue". Ex: https://github.com/hapijs/lab

[Aaron Bartell]

Regardless of where the docs end up, I started the conversion of dW to this repo.

Here you can find a bitbucket snippet where I converted the first couple APIs.

A couple notes:

• LF (line feed) isn't supported in Markdown tables on Bitbucket, so I create a new table row with cells to the left that are blank.
• Use [TOC] at the top of the doc and it will create a table of contents based on the various hash levels (i.e. # translates to <h1>, ## translates to <h2>, etc)

[Former user]

I am curious what you're searching for and not finding. When I search for open source project documentation it is usually the Github/Bitbucket repo that shows up in the top 5 organic search entries (coupled with oodles of StackOverflow entries).

No. This is a misleading 'lobby' (bad logic). That is, when you use part of the project name, then Github/Bitbucket project shows up (google 'python itoolkit'). When you use something inside subdir/README.md, you will not even see the Github/Bitbucket project (google 'python iCmd5250').

This /docs/README.md is a bad idea, because you will remove IBM i documentation from search engines (google).

[Aaron Bartell]

When you use something inside subdir/README.md, you will not even see the Github/Bitbucket project (google 'python iCmd5250').

I am following you now. That's very unfortunate the subdirs aren't indexed. What's interesting is a search for "iCmd5250" picked up the one Github (which is in a subdir). I wonder if it is a bitbucket thing.

I've made a change to the Python iToolkit Bitbucket Wiki (added "iCmd5250") to see if Google picks that up. Stay tuned!

[Former user]

I am following you now. That's very unfortunate the subdirs aren't indexed.

Cool! Now we are on the same page. Never fight google search (or bing, etc.). Actually, a certain big unnamed company (cough), figured 'playing search ball' was a good idea with "on line" documentation.

"iCmd5250" picked up the one Github (which is in a subdir

I believe web search works due to Club Seiden web page as 'home' for url. Aka, Club Seiden has many visitors for a variety of reasons. Perhaps, also there is no SHA-1 in this link (SHA-1 key may be a google 'no no' find).

https://github.com/Club-Seiden/python-for-IBM-i-examples/blob/master/non-wheel/bottle-example/sample.py