dnncommunity / dnndocs Goto Github PK

In the Administrators section we have some duplicate content and I believe it may be this way across all "personas" index pages in the docs project.

Administrators > Microservices > About Micro-Services

has the same content as

Administrators > MicroServices > Administrators-Microservices-Overview

The question is how do we handle a situation where the current version of the docs is for DNN 10. We've already released and have branches for DNN 8 and DNN 9. A change is made to a topic that applies to DNN 8-10. How do we handle getting that change in the DNN 8 branch merged into the DNN 9 and DNN 10 branches.

I think our best option is to use cherry picking. This a git command that allows us to take a specific commit in one branch and copy it into another branch. Its use is discouraged in development scenarios primarily because you are creating a copy of the changes in the commit and making a new commit on the new branch with those changes. In a development scenario, this isn't idea. because you lose the history of the original commit. However, this isn't a development scenario. We don't need to track changes to the content across time over all branches.

In order to do this, we should adopt a policy of 1 commit per file, unless the same change is made across multiple topics. Since cherry picking works with commits, the more granular we can make those commits, the easier it will be to get just the content we want. Plus, you can cherry pick multiple commits in one command.

How Cherry Picking Works

Let's say we have a master branch with the current DNN version (say, DNN10) and have a branch for DNN8 and DNN9. We'll call these branches: dnn10 dnn9 dnn8 and master (which contains the current release of the docs, regardless of DNN version). Let's also assume that changes were made to a topic in the dnn8 branch that should also apply to dnn9 and dnn10.

Step One: Get the Hash of the Source Commit

The first thing we need to do is identify the specific commit(s) we want to merge.

git checkout dnn8

git log --oneline
5dfe882 Changed File Title to Creating Users
12dc37f Added Creating Portal topic

For this example, we'll use 5dfe882

Step Two: Switch to the Target Branch

git checkout dnn9

Step Three: Do the Cherry Pick

git cherry-pick 5dfe882

You can pull in multiple commits by simply adding them to the command:

git cherry-pick 5dfe992 12dc37f

Step Four: Push your Changes

git push

Update API Section Tables & Callouts to Markdown Syntax

Update Content Manager Section Tables & Callouts to Markdown Syntax

The Admin > Glossary markdown formatting needs to be updated to included bolded words and callouts.

The markdown in this file has not been updated and needs table formatting

In addition to the Codeplex URLs called out by #84, there are many other URLs that are pointed to old domains or pages.

For example, Bruce Chapman's site is offline, so we could use an archive.org URL to his blog posts. The DNN Forge has been taken down, so references to that could be removed. There are also some placeholder usages of google.com that can be removed.

This content is currently not formatted using markdown syntax and needs to be updated

The table that is present at the bottom of this page
http://www.dnnsoftware.com/docs/community-managers/included-modules/module-user-badges.html

seemed to be lost in the migration/conversion to docFx. There is no syntax for a table in the markdown file for the page.

dnn-docs\content\community-managers\included-modules\module-user-badges\090200\index.md

We need to update this to render the table. This problem likely exists on several pages.

Currently the DocFX we're building is using the old file structure/organization which places content (articles) in index.md in the version folder (ie. 09.02.00) inside a topic folder (which may be inside another topic folder), inside a section folder like so:

dnn-docs/content/administrators/building-your-site/building-your-site/090200/index.md

Images are placed alongside the index.md file.

While this makes sense to prevent naming conflicts, DocFX effectively duplicates that tree structure in its table of contents (TOC), resulting in a deep tree structure that doesn't really add to the user experience.

We need to rethink the content organization and/or determine how to use DocFX's TOC mechanisms to provide quick and effective navigation via TOC while still preventing naming conflicts.

https://github.com/DNNCommunity/DNNDocs/blob/master/content/administrators/glossary/index.md

A tip callout references 10 Pound Gorilla's Skinning Tool. This link does not point to the tool. It points to the 10 Pound Gorilla home page. This link should be corrected or removed if the tool no longer exists or is out of date.

Open issue and instructions for reformatting the individual markdown pages that are related to the warnings about broken links when building.

There are two primary issues that need to be resolved for each markdown file.

1. Images that currently exist in a sub-folder for a particular topic need to be moved to the main images folder in the root
2. The toc at the top of the file needs to be removed and sub-headings need to be added instead which build the sidebar menu.

See DNNCommunity/dnn-docs@f8f7fa0

There are characters that do not need to be here on this page.

As Clint was demoing his change to the Security page, I noticed that the link to the security center was using HTTP instead of HTTPS. Since the dnnsoftware.com site is served over HTTPS now, we should use HTTPS for those links. This would prevent attackers from being able to intercept links to security information. It's also just avoids an HTTPS redirect.

We can also update other URLs, since almost all of the sites the docs link to are on HTTPS now.

When building, a very long list of warnings is generated similar to this:

[18-11-28 05:39:47.057]Warning:[BuildCommand.BuildCore.Build Document.LinkPhaseHandlerWithIncremental.ConceptualDocumentProcessor.Save](content/developers/included-modules/config-module-social-groups/090200/index.md#L42)Invalid file link:(~/content/developers/included-modules/config-module-social-groups/090200/img/scr-modulesettings-SocialGroups-AutoConfig.png).

We need the following:

• A build server
• A temporary public-facing server to display results

I can run this with my Jenkins server and output it to an S3 site or my server as a static site. Thoughts?

The Developers persona needs a section home page and section sidebar navigation

Enable DocFX searching via Lunr. Later we can look at improving this with Algolia's DocSearch.

Update Common Section Tables & Callouts to Markdown Syntax

Under the Administrator's section there are several files that need the markdown updated for a few items:

• Callouts
• Bolded words
• Removing the 1 & 2 footnote 'artifacts' from the previous system

These issues are present because initially the goal was simply to convert all tables to markdown. After the table conversion started the updated syntax for callouts was created and shared. During this phase making words bold was not a priority.

Now I will go in and make these updates under the Administrators section (currently the largest section of the docs). The other sections do not need this treatment.

There is a "TIP" callout on the Administrators > Assets > Add Assets file that needs to have the markdown updated. There are also some words that need to be bolded.

The Content Managers persona needs a home page and section sidebar navigation

When linking to common content, the user is taken out of their "section" of the docs. This causes a context shift and confusion for the user.

For example, Developers who click on "Set Up DNN" are taken to the common setup information inside "Administrators". There is no way for them to get back to their previous page and they may not even be aware they are in a new section.

The text is currently plain and needs to have bold formatting & the > [TIP!] syntax applied

Clicking the API link in the main navigation results in a 404.

In modern browsers, typing in the search box now shows a red "Not Secure" because the site is not using SSL. Rectify that.

The archives have moved from CodePlex to GitHub. The links in the docs need to be changed to reflect the new location.

Example: content/administrators/release-notes/relnotes-2013-jan-09/index.md

Implement initial custom template based on default template

Since moving the repo, removing it's connection to my original repo, and removing the docfx branch, the setup docs need to be updated to reflect the change.

These artifacts are from the old system and need to be removed.

Current the standard DNN favicon file is being used. However, it would be nice to replace that with a white version that matches the D in the DNNDocs logo.

Update Designer Section Tables & Callouts to Markdown Syntax

The favicon needs to be updated to the DNN favicon.

Currently, the navigation links for Administrators | Designers | Developers have the wrong URLs based on an older folder structure.

Formatting is missing markdown syntax and needs to be updated.

There is a "TIP" callout that needs it's markdown formatting updated so that it will render properly on the page.

Update Developer Section Tables & Callouts to Markdown Syntax

The Administrators persona section requires a "home" page and section navigation sidebar.

A new page was added to the current (soon-to-be-old) DNN Docs center that highlights the new DNN integration with Kayako. This page needs to be added to the DocFx version (soon-to-be-new) of DNN Docs

https://www.dnnsoftware.com/docs/administrators/connectors/kayako-messenger-integration.html

This page has important info that needs to be called out

There is currently text for hyperlinks that are not actually hyperlinked.

Update Community Managers Section Tables & Callouts to Markdown Syntax

The Designers persona needs a home page and navigation sidebar

The quality of the current DNNDocs logo needs to be improved and vertical spacing needs to be increased above/below the logo.

Since the data dump some new "Release Notes" have been added to the DNN Docs site. We need to be sure to include those updated release notes in the new DNN Docs site

https://www.dnnsoftware.com/docs/developers/product-versions.html

General layout and style of the table of contents sidebar needs to be improved. Following are a few goals.

• Widen container(s) to help prevent items from wrapping as much as possible
• Remove plus/minus sign to allow extra width for items
• Improve styling to behave more like a typical accordion

Currently there is no direct link to the release notes other than search. This needs to be pulled out to be more visible and to be crawlable by search engines.

When I owned the repo, this link worked. Now that we've moved it to a new location, the links no longer work. They result in a GitHub 404 error.