Links on Documentation Page Broken

[ritchiecarroll]

https://github.com/GridProtectionAlliance/openPDC/wiki/Documentation

These pages seem to have lost many of their previous links.

Validate your last updates.

Thanks, Ritchie

[ajstadlin]

Thank you for letting me know.  I will work through them over the next few weeks and fix them up. Would you prefer the fixed documentation to be submitted as Pull Requests or as direct GitHub edits?    AJ

----- Original Message -----

From: "J. Ritchie Carroll" notifications@github.com To: "GridProtectionAlliance/openPDC" openPDC@noreply.github.com Sent: Tuesday, September 13, 2016 8:22:12 AM Subject: [GridProtectionAlliance/openPDC] Links on Documentation Page Broken (#28)

https://github.com/GridProtectionAlliance/openPDC/wiki/Documentation

These pages seem to have lost many of their previous links.

Validate your last updates.

Thanks, Ritchie

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub , or mute the thread .

[ritchiecarroll]

Hi AJ - if you would like to take a look please feel free to do direct check-ins...

[ajstadlin]

Thank you for the quick reply. 

Direct editing/checkins are easiest because I can test the links in github's editor/preview as I go.  I would also like, where practical, convert some of the content from raw HTML to MD markdown.

AJ  

----- Original Message -----

From: "J. Ritchie Carroll" notifications@github.com To: "GridProtectionAlliance/openPDC" openPDC@noreply.github.com Cc: "ajstadlin" ajstadlin@gridtrak.com, "Comment" comment@noreply.github.com Sent: Tuesday, September 13, 2016 9:56:51 AM Subject: Re: [GridProtectionAlliance/openPDC] Links on Documentation Page Broken (#28)

Hi AJ - if you would like to take a look please feel free to do direct check-ins...

— You are receiving this because you commented. Reply to this email directly, view it on GitHub , or mute the thread .

[ajstadlin]

I noticed that Stephen Jenks is working on the document.  Direct editing is probably best to avoid version conflicts - thank you for confirming this is OK in your previous email. The reason the links are broken is that they are Relative links; i.e. relative to the project's github Wiki.  The current wiki documents are stored in the project's GitHub repository, not the GitHub wiki.    I request that you or other high level project manager make a command decision regarding this issue:   1.  Maintain the Project Wiki documentation in the GitHub Wiki.  Relative URLs will work and enables editing privileges independent of the project repository. or 2.  Maintain the Project Wiki documentation in the GitHub Project Repository.  Absolute URLs are and project editing privileges are required. or 3.  Both 1 and 2  - not really a good idea since it is almost double work unless a LINK translation utility is developed and used.   I personally prefer #2 because the documentation can be easily cloned with the project and GitHub provides the same viewing and direct editing capability.  I have not checked to see if the  #1 option, GitHub Wiki can be bulk exported.  #1 requires copying the current documentation from the repository to the Wiki pages which might be a manual, create each wiki page and copy content, process.   Although I personally prefer maintaining the documentation within the project repository, I will work with the methods that the GPA project managers want to use.   AJ.

----- Original Message -----

From: "J. Ritchie Carroll" notifications@github.com To: "GridProtectionAlliance/openPDC" openPDC@noreply.github.com Sent: Tuesday, September 13, 2016 8:22:12 AM Subject: [GridProtectionAlliance/openPDC] Links on Documentation Page Broken (#28)

https://github.com/GridProtectionAlliance/openPDC/wiki/Documentation

These pages seem to have lost many of their previous links.

Validate your last updates.

Thanks, Ritchie

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub , or mute the thread .

[ritchiecarroll]

Let's just stick with simple option 2, I'll have Stephen Jenks coordinate with you on changes.

Thanks! Ritchie

[chefsteph9]

AJ,

I had started to go to option 1 because we are trying to put all of our documentation into one wiki using Dokuwiki. Link to GPA wiki. That way each project's wiki could be exported to Dokuwiki as a section of the wiki. If we maintained the project wiki in the GitHub Wiki, then it would be easy to clone the wiki, use a tool called pandoc (also on Github) to convert from GitHub markdown to Dokuwiki markup., and move it into the Dokuwiki wiki. I have tested it in our wiki playground and the relative links still work in Dokuwiki after I convert from markdown. So basically, I've been doing option 1 so that each project's wiki can be a part of our overall documentation in Dokuwiki.

I am willing to work with either option but option 2 will make it harder to incorporate individual project wikis into the Dokuwiki wiki.

PS: I know the openPDC GitHub wiki is a bit of a mess right now, most of the relative links don't work yet since I haven't finished transferring everything over from the project repository, I've been doing some things to test what works in both GitHub and Dokuwiki, and I also started using CamelCase page naming but I have decided to go back to page_names_with_underscores but not everything is converted back yet. (CamelCase page names has definitely not been my brightest idea). So bear with me on that. I haven't touched the wiki in the project repository though, so that should still be fine. If we do decide to go with option 1, then I'll open a new project and move the wiki to that until it's finished so people aren't confused by the unfinished wiki.

Stephen Jenks.

[ajstadlin]

Stephen,

Thank you for your feedback. It looks like you have methods in place to manage the wiki documents' export, authoring, conversion, and viewing. The biggest advantage of relative links in the documents is that they are more portable than absolute links.

Per your feedback, I am now convinced that Relative links will be better moving forward. Thank you.

I will check out Dokuwiki and pandoc and see if I can setup a workable playground.

AJ

----- Original Message -----

From: "Stephen Jenks" notifications@github.com To: "GridProtectionAlliance/openPDC" openPDC@noreply.github.com Cc: "ajstadlin" ajstadlin@gridtrak.com, "Comment" comment@noreply.github.com Sent: Tuesday, September 13, 2016 1:52:17 PM Subject: Re: [GridProtectionAlliance/openPDC] Links on Documentation Page Broken (#28)

AJ,

I had started to go to option 1 because we are trying to put all of our documentation into one wiki using Dokuwiki. Link to GPA wiki . That way each project's wiki could be exported to Dokuwiki as a section of the wiki. If we maintained the project wiki in the GitHub Wiki, then it would be easy to clone the wiki, use a tool called pandoc ( also on Github ) to convert from GitHub markdown to Dokuwiki markup., and move it into the Dokuwiki wiki. I have tested it in our wiki playground and the relative links still work in Dokuwiki after I convert from markdown. So basically, I've been doing option 1 so that each project's wiki can be a part of our overall documentation in Dokuwiki.

I am willing to work with either option but option 2 will make it harder to incorporate individual project wikis into the Dokuwiki wiki.

PS: I know the openPDC GitHub wiki is a bit of a mess right now, most of the relative links don't work yet since I haven't finished transferring everything over from the project repository, I've been doing some things to test what works in both GitHub and Dokuwiki, and I also started using CamelCase page naming but I have decided to go back to page_names_with_underscores but not everything is converted back yet. (CamelCase page names has definitely not been my brightest idea). So bear with me on that. I haven't touched the wiki in the project repository though, so that should still be fine. If we do decide to go with option 1, then I'll open a new project and move the wiki to that until it's finished so people aren't confused by the unfinished wiki.

Stephen Jenks.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub , or mute the thread .

[ritchiecarroll]

Work in progress...

[ajstadlin]

I performed a few tests to compare the merits of relative links VS absolute links in the wiki documents.

1. Absolute Links will always work until the documents the links are pointed to are moved.
2. Relative Links work only within the context of the path the service provider prepends them with. In this case, the GitHub repository prepends the document's repository path VS the GitHub wiki prepends the document's wiki path. This allows the documents with relative links to be portable.

OK, on the surface, Relative Links look like the better choice. However, I started running into snags with the GitHub wiki.

Snag 1: I think that every file that the GitHub wiki requires will need to be in the side bar files list. This will significantly clutter the sidebar.

Snag 2: I'm not sure how to add non-markup files to the GitHub wiki so they can have relative links to them.

My personal recommendations are:

Recom 1: Only 1 Wiki. This will save duplicating work and troubleshooting. I recommend the wiki be the GPA hosted DokuWiki. This will provide the best life cycle control for the documentation.

Recom 2: The GitHub Wiki should be minimal and used like a "Table of Contents" or FAQ. Its links should point to appropriate content in the GPA DokuWiki or related project repository content.

Recom 3: The current project Source/Documentation/wiki can gradually be replaced with DokuWiki formatted files. The updated files should be arranged in folders and using relative links compatible with the GPA DokuWiki namespace(s). This will eliminate the need to convert between document formats every time a document is revised.

[ajstadlin]

Recommendation 4: If maintaining GitHub markdown files for the DokuWiki in the project repository, I would propose the following:

P.1) Compose a script that can be used to automatically convert the primary wiki files to the secondary format.

P.2) If there are any repeatable conversion issues, compose a simple script or utility to fixup the files after conversion.

For example: If it is decided that the primary wiki files are the Project GitHub Repository Documentation/wiki files in GitHub markdown format, then the secondary DokuWiki files could be generated from those files with a script that automates converting the GitHub markdown files to DokuWiki files. The resulting secondary files can then be stored in GitHub Project Repository Documentation/dokuwiki files.

Else, if it is decided that the primary wiki files are the GPA hosted DokuWiki files, then these could be exported or backed up to GitHub Project Repository Documentation/dokuwiki files. The conversion script would then be run to convert the Documentation/dokuwiki files to Documentation/wiki files.

What I think is important is that the documentation workflow primarily progress in a single direction. I think the direction should be a command decision by the project leaders.

My personal preference now, after thinking (and more thinking) about it, is:

AJ.1) Use the GitHub Project Repository Documentation/wiki markdown_github format files as the primary documentation and compose a script to convert those files to dokuwiki format and save them in the Project Repository Documeation/dokuwiki. The markdown_github files should use a namespace/folder layout and relative links that matche the GPA main DokuWiki as much as possible to minimize conversion exceptions and troubleshooting.

AJ.2) The GitHub Sidebar Wiki for each GitHub hosted GPA project to have a standard set of documents common to all of the GPA projects. This will provide a consistent UI for people visiting the GPA projects on GitHub. For example:

• Overview
• Getting Started
• Frequently Asked Questions
• Documentation
• Related Projects

AJ.3) The GitHub Sidebar wiki documents to be composed for the purpose of providing easy navigation links to content in the GPA DokuWiki and the Project Repository. The GitHub sidebar wiki documents should be a simple and concise as possible - to require minimal maintenance.

Your feedback is important since these practices can be applied to all of the GPA projects and on-line documentation.