blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-09-01 03:02:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update files for reviewers

Browse Source
This commit is contained in:
Ryan Watters
2017-02-21 14:56:42 -06:00
parent 5d0694a47f
commit a1512e501f
2 changed files with 51 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content-changes.md
+11 -18
View File
@@ -1,19 +1,16 @@
<!-- MarkdownTOC -->
# Content Reorganization
- [Changes to Existing Content Sections][changes-to-existing-content-sections]
- [Extras][extras]
- [Tutorials][tutorials]
- [Content Organization \(Site\)][content-organization-site]
- [Content Organization \(Source\)][content-organization-source]
- [Changes to Existing Content Sections](#changes-to-existing-sections)
- [Extras](#extras)
- [Tutorials](#tutorials)
- [Getting Started](#getting-started)
- [Content Organization: \(Site Navigation\](#content-organization-site-navigation)
- [Content Organization: \(Source\)](#content-organization-source)
<!-- /MarkdownTOC -->
<a name="changes-to-existing-content-sections"></a>
## Changes to Existing Content Sections
## Changes to Existing Sections
The following is an *abbreviated* listing and only includes the *larger* changes to content organization. These changes do not include copy edits for consistent usage, which easily numbers in the thousands at this point.
<a name="extras"></a>
### [Extras](http://gohugo.io/extras)
* This section no longer exists in the new documentation site
@@ -22,7 +19,6 @@ The following is an *abbreviated* listing and only includes the *larger* changes
* **Aliases** Incorporated into `/content-management/url-management/`
* **Analytics** Incorporated into /templates/partial-templates/#built-in
<a name="tutorials"></a>
### [Tutorials](http://gohugo.io/tutorials)
* Moved all installation guides to /getting-started/install-hugo/
@@ -31,16 +27,13 @@ The following is an *abbreviated* listing and only includes the *larger* changes
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
* Aliases added to new pages and in-page links updated throughout
<a name="content-organization-site"></a>
## Content Organization (Site)
## Content Organization: Site Navigation
The following is a list of weights for the newly restructure site architecture
<a name="content-organization-source"></a>
## Content Organization (Source)
## Content Organization: Source
**2017-02-21 New Content Reorganization**
**Updated 2017-02-21**
```
.
strategy.md
+40 -47
View File
@@ -1,72 +1,63 @@
<!-- MarkdownTOC -->
- [Assumptions][assumptions]
- [Goals][goals]
- [Audience][audience]
- [Persona][persona]
- [End User: Developer][end-user-developer]
- [End User: Themes \(i.e. blogger/author/\)][end-user-themes-ie-bloggerauthor]
- [Requirements][requirements]
- [Technical][technical]
- [SEO][seo]
- [Editorial/Content][editorialcontent]
- [UX][ux]
- [Author Experience \(AX\)][author-experience-ax]
- [Visual Design][visual-design]
<!-- /MarkdownTOC -->
- [Assumptions](#assumptions)
- [Goals](#goals)
- [Audience](#audience)
- [Persona](#persona)
- [End User: Developer](#end-user-developer)
- [End User: Themes \(i.e. blogger/author/\)](#end-user-themes-ie-bloggerauthor)
- [Requirements](#requirements)
- [Technical](#technical)
- [SEO](#seo)
- [Editorial/Content](#editorialcontent)
- [UX](#ux)
- [Author Experience \(AX\)](#author-experience-ax)
- [Visual Design](#visual-design)
**Updated 2017-02-21**
This is a *very* schlocky version of the documentation I'd put together in my professional life. That said, I think the following pieces are still important and should provide some insight as to how I've approached reworking the Hugo documentation over the last three months.
<a name="assumptions"></a>
## Assumptions
> **Note**: These assumptions are empirical; i.e. the result of me spending a large (and potentially unhealthy) amount of time on the [Hugo Discussion Forum](https://discuss.gohugo.io).
* The current documentation is...
* The current documentation is
* confusing for new users
* a common complaint in the Hugo forums [example discussion 1][],[example discussion 2][]
* Lacks structure and therefore...
* doesn't scale (as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown).
* lacks structure and therefore
* doesn't scale, as demonstrated by [patch pages](http://gohugo.io/taxonomies/templates/) that seem out of place or require unnecessary drilldown)
* is inconsistent in its terminology, style, and (sometimes) layout
* limits the efficacy of Alogolia's document search feature
* Does not itself leverage Hugo's more powerful feature (e.g., there is only *one* archetype and five shortcodes for what is ultimately a complex documentation site).
* Leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* Assumes a higher level of Golang proficiency than is realistic for newcomers to the language or web development in general.
* If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*.
* Content modeling is king
* Go DRY (e.g. with shortcodes)
* Require metadata
* limits the efficacy of Alogolia's document search feature through redundant content groups, headings, etc
* does not leverage SEO for external search engines
* does not leverage Hugo's more powerful feature (e.g., there is only *one* archetype); leveraging these features would help address the aforementioned shortcomings (i.e., scalability, consistency, and search)
* assumes a higher level of Golang proficiency than is realistic for newcomers to the Golang programming language or to web development in general.
* If you don't make it *very easy* for authors to contribute to documentation correctly, they will inevitably contribute *incorrectly*;
* content modeling is king
* go DRY (e.g., with shortcodes)
* set required metadata
<a name="goals"></a>
## Goals
Hugo documentation should...
* reduce confusion surrounding `list` vs `section` vs `page` vs `content type`,etc., and thereby
* reduce confusion surrounding Hugo concepts as `list`, `section`, `page`, `content type`, etc. and thereby
* make it easier for new users to get up and running
* create better consistency and scalability Hugo-dependent projects (namely, http://themes.gohugo.io)
* reduce frequency of such questions in the Hugo Discuss Forum
* not require any degree of Golang proficiency from end users.
* That said, Hugo *can* act as a bridge for those interested in learning Golang (e.g., by including `godocref` as a default front matter field in [`archetypes/functions.md`](https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md)).
* create better consistency and scalability for Hugo-dependent projects (viz., http://themes.gohugo.io)
* reduce frequency of questions surrounding said concepts in the Hugo Discuss Forum
* not require or assume any degree of Golang proficiency from end users;
* that said, Hugo can&mdash;and *should*&mdash;act as a bridge for users interest in learning Golang (e.g., by including `godocref` as a default front matter field in [`archetypes/functions.md`][functionarchetype].
* be easy to expand and edit for contributors Editing and expanding documentation should be easiest for *contributors**, whereas usage of documentation should be easiest for *end users*.
* be equally accessible via mobile, tablet, desktop, *and* offline.
* not include an "extras" section because [this is the last place end users look to learn about Hugo](https://discuss.gohugo.io/t/site-with-different-lists-of-sections/5536/3). Instead all "extras" should be integrated into a new
* easily scaffold for future multilingual versions
<a name="audience"></a>
## Audience
* Primary: Web developers interested in static site generators
* Secondary: Web publishers (bloggers, authors)
* Tertiary: Web developers interested in learning Golang
<a name="persona"></a>
## Persona
<a name="end-user-developer"></a>
### End User: Developer
* Limited proficiency in Git and DVCS
@@ -76,17 +67,14 @@ Hugo documentation should...
* proficiency in the English language
* proficiency in other languages (for future multilingual versions)
<a name="end-user-themes-ie-bloggerauthor"></a>
### End User: Themes (i.e. blogger/author/)
* Limited proficiency in the command line/prompt
* Proficiency in a supported content format (specifically markdown)
* Access to static hosting but with limited proficiency in basic deployments
<a name="requirements"></a>
## Requirements
<a name="technical"></a>
### Technical
- [X] Built with Hugo
@@ -94,7 +82,6 @@ Hugo documentation should...
- [X] Front-end build tools for concatenation, minification
- [ ] CDN
<a name="seo"></a>
### SEO
- [X] [Open Graph Protocol](http://ogp.me/)
@@ -105,14 +92,13 @@ Hugo documentation should...
- [ ] SSL
- [ ] AMP
<a name="editorialcontent"></a>
### Editorial/Content
- [X] Basic style guide
- [X] Contribution guidelines (see [working draft on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/))
- [X] Standardized content types (i.e, [see current archetypes](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes)
- [X] New Content Model, including taxonomies ([see tags page]())
- [ ] DRY. New shortcodes for repeat content (e.g., list of aliases, list of page variables)
- [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others)
- [X] New site architecture and content groupings
- [ ] Examples pulling from a single sample website (including in docs source) for consistent code samples or in-page tutorials
@@ -125,7 +111,6 @@ Hugo documentation should...
> The Hugo documentation is a joint effort between the Hugo maintainers and the open-source community. Hugo documentation is designed to promote Hugo, the world's fastest, friendliest, and most extensible static site generator. Hugo documentation is the primary vehicle by which the Hugo team reaches our target audiences. When visitors comes to our site, we want them to install Hugo, developer a new site in Hugo, and share their progress with the community at large.
<a name="ux"></a>
## UX
- [ ] Share buttons
@@ -134,13 +119,19 @@ Hugo documentation should...
- [X] Dual in-page navigation
- [X] Smooth scrolling
<a name="author-experience-ax"></a>
## Author Experience (AX)
- [X] Easy scaffolding of content types (CLI)
- [X] Type-based content storage model and scope (archetypes)
<a name="visual-design"></a>
## Analytics
- [X] Google Analytics
- [ ] Content groupings in GA to measure usage and define content gaps
- [ ] Automated reports
> **Note:** These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
## Visual Design
- [X] Clean typography with open-source font
@@ -156,5 +147,7 @@ Hugo documentation should...
- [X] Abstracted color palette
- [X] Abstracted typefaces (multiple open-source fonts available)
[example discussion 1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810
[example discussion 2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891
[functionarchetype]: (https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md))