Documentation site must support multiple versions of the documentations

[kochhar]

The documentation site must allow visitors to reference documentation for past versions of the platform.

[lakhanmandloi]

Hi @kochhar ,

We need to have a quick discussion on following points -

1. What all sections will have multiple versions. Only dev docs or entire docs pages ? etc
2. What should be the url pattern for the same.

Let me know when we can do a short discussion . Thanks!

[lakhanmandloi]

cc: @coolbung @parthlawate

[kochhar]

All docs pages can have multiple versions -- feature documentation will also evolve with new releases.

Suggestion is we have either: a. https://docs.sunbird.org/v/ b. https://www.sunbird.org/docs/v/

On Mon, Nov 13, 2017 at 1:00 PM Lakhan Mandloi notifications@github.com wrote:

Hi @kochhar https://github.com/kochhar ,

We need to have a quick discussion on following points -

1. What all sections will have multiple versions. Only dev docs or entire docs pages ? etc
2. What should be the url pattern for the same.

Let me know when we can do a short discussion . Thanks!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-343835590, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqkBpSDAjM6nUrdG0h_gx07SHT0Maks5s1-_-gaJpZM4QQxQT .

[lakhanmandloi]

Hi @kochhar ,

Can you pls check this - https://lakhanmandloi.github.io/docs/ ? Is this what you expect ?

[kochhar]

Hi Lakhan, this is a great start.

Some notes

1. I don't think we have to provide the ToC for the previous versions on the landing page
2. The versions available on the landing page should have a date attached to each one.
3. Switching versions should be possible from any page
4. When switching, the current page should be preserved
5. In the left nav, the elements should not be Architecture 2.0 and Product Features 2.0

Will give you more details after a detailed review this afternoon.

On Mon, Dec 18, 2017 at 5:00 PM Lakhan Mandloi notifications@github.com wrote:

Hi @kochhar https://github.com/kochhar ,

Can you pls check this - https://lakhanmandloi.github.io/docs/ ? Is this what you expect ?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-352400471, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqpCVEID2ozQM_gQrnGr-od2tc8bWks5tBkzAgaJpZM4QQxQT .

[lakhanmandloi]

Hi @kochhar ,

Here are my comments -

1. I don't think we have to provide the ToC for the previous versions on the landing page - I do not get your point ? I mean why not on old versions?
2. The versions available on the landing page should have a date attached to each one. - Done
3. Switching versions should be possible from any page - Done, The only problem i see is, if same page is not available in another version , so the drop-down should not have that version value. Will try to fix this issue asap.
4. When switching, the current page should be preserved - Done
5. In the left nav, the elements should not be Architecture 2.0 and Product Features 2.0 - That was just to highlight the sidebar changes with the version change. Cleaned.

Please let me know if you have more feedback.

Thanks!

[kochhar]

Hi @lakhanmandloi,

Reasoning for not having ToC on the landing page are:

1. The landing page will start to get crowded as we increase the number of versions. It also gives a lot of emphasis on past versions -- which is not the intention.
2. The top-level ToC could change between versions. I'm also thinking of restructuring the landing page and it would be easier to do that without the past versions ToC on the same page.

On Tue, Dec 19, 2017 at 7:17 PM Lakhan Mandloi notifications@github.com wrote:

Hi @kochhar https://github.com/kochhar ,

Here are my comments -

1. I don't think we have to provide the ToC for the previous versions on the landing page - I do not get your point ? I mean why not on old versions?
2. The versions available on the landing page should have a date attached to each one. - Done
3. Switching versions should be possible from any page - Done, The only problem i see is, if same page is not available in another version , so the drop-down should not have that version value. Will try to fix this issue asap.
4. When switching, the current page should be preserved - Done
5. In the left nav, the elements should not be Architecture 2.0 and Product Features 2.0 - That was just to highlight the sidebar changes with the version change. Cleaned.

Please let me know if you have more feedback.

Thanks!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-352755362, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqkiw-T6Ys-bQ1MDZVCHslbRxI_yjks5tB76BgaJpZM4QQxQT .

[lakhanmandloi]

Hello @kochhar , Thank you for clearing. :) Got your point and i agree with it.

Do you have any more feedback on same? Also when do we expect to make it live?

[kochhar]

Hi @lakhanmandloi, where are the version strings (1.0 / 2.0) coming from? Let's also circulate the in-page version picker with a few others for feedback on look&feel and placement.

On Tue, Jan 2, 2018 at 12:34 PM Lakhan Mandloi notifications@github.com wrote:

Hello @kochhar https://github.com/kochhar , Thank you for clearing. :) Got your point and i agree with it.

Do you have any more feedback on same? Also when do we expect to make it live?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-354711839, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqhSt5Z3maJ7SwTJrJW6FHk4iBjngks5tGdUSgaJpZM4QQxQT .

[lakhanmandloi]

Hello @kochhar ,

We maintain the versions in config file and mark which one is the latest version. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_config.yml . This information can be used at various places.

Versions drop-down in sidebar is dynamically based on the values mentioned in config file. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_includes/version.html

For each version sidebar menu could be different so for each version a sidebar file will need to be generated with name format sidebar-{{Version no.}}.html this file will automatically get added on the pages of specific version docs. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/tree/dev/_includes & https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_layouts/page.html#L3

For the version in URL string we create folders in versioned manner - https://github.com/lakhanmandloi/lakhanmandloi.github.io/tree/dev/docs

The URL structure is now like - {{folder name}} / {{ sub-folder name}} / {{sub sub folder name}} / {{ file name }}

Please let me know to whom i should share to get feedback ?

Thank you ! :)

[kochhar]

@lakhanmandloi how do we know which version corresponds to each release? This must be provided as input via repository tags.

On Tue, Jan 2, 2018 at 2:53 PM Lakhan Mandloi notifications@github.com wrote:

Hello @kochhar https://github.com/kochhar ,

We maintain the versions in config file and mark which one is the latest version. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_config.yml . This information can be used at various places.

Versions drop-down in sidebar is dynamically based on the values mentioned in config file. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_includes/version.html

For each version sidebar menu could be different so for each version a sidebar file will need to be generated with name format sidebar-{{Version no.}}.html this file will automatically get added on the pages of specific version docs. - https://github.com/lakhanmandloi/lakhanmandloi.github.io/tree/dev/_includes & https://github.com/lakhanmandloi/lakhanmandloi.github.io/blob/dev/_layouts/page.html#L3

For the version in URL string we create folders in versioned manner - https://github.com/lakhanmandloi/lakhanmandloi.github.io/tree/dev/docs

The URL structure is now like - {{folder name}} / {{ sub-folder name}} / {{sub sub folder name}} / {{ file name }}

Please let me know to whom i should share to get feedback ?

Thank you ! :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-354727208, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqqOYRxmPrR6uPsGjXA0stBtyahM6ks5tGfV2gaJpZM4QQxQT .

[lakhanmandloi]

@kochhar Just to clear my confusion - for git tag 1.0 - version 1.0 documentation should be build as soon as we created git tag 2.0 - version 2.0 documentation should be added to the site and 1.0 version docs should move to previous version sections. So the same md file will build multiple versions of documentation based on git tags.

Please correct me if something missing or wrong.

[kochhar]

Tags is one example input. It can also be built based on config. Or could be maintained in the source files also. Could you add to the wiki page or google doc to describe how the mapping is maintained.

On Tue, Jan 2, 2018 at 4:12 PM Lakhan Mandloi notifications@github.com wrote:

@kochhar https://github.com/kochhar Just to clear my confusion - for git tag 1.0 - version 1.0 documentation should be build as soon as we created git tag 2.0 - version 2.0 documentation should be added to the site and 1.0 version docs should move to previous version sections. So the same md file will build multiple versions of documentation based on git tags.

Please correct me if something missing or wrong.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/project-sunbird/project-sunbird.github.io/issues/29#issuecomment-354740018, or mute the thread https://github.com/notifications/unsubscribe-auth/AAGVqlRlWgX_-R2BZ6UFh_Uh95PuJXARks5tGggOgaJpZM4QQxQT .

[lakhanmandloi]

@kochhar - The current system developed supports publishing new version from config file itself. I will soon share a doc to describe the process. There is some scope to improve ease of maintenance. Working on same to improve as much as we can.