Office workers collaboratively writing documentation.

Product: Design Docs for a Static Blog and Portfolio Website

Ok, so I built the new portfolio website and now I need some content. Luckily, I’d generated some simple documentation for this simple website before building it, so that should make for a good post to fill some space (and showcase “Documentation” as a skill). It’s just a static portfolio and blog, there is no backend, no CDN, and deployment is pretty simple; the only docs I made for this website is a Software Requirements Specification and a Technical Requirements Specification

Software Requirements Specification

Intro

  • Purpose

    • To showcase services offered, work and education history, projects and other career-relevant materials.

  • Audience

    • Potential employers, clients and others seeking information about the subject’s skills and experience.

  • Scope

    • This document outlines functional and non-functional requirements for a static website with pages (or sections) for Portfolio, Blog and Contact.

System Overview

  • Home Page

    • Services Offered
      • a list of the general services that the subject offers
      • a list of the main technologies that the subject uses
    • Portfolio Section
      • a list of projects that the subject has recently worked on
    • Resume Section
      • a list of education and professional work experiences that the subject has participated in

  • Contact Page

    • a basic form for getting in touch
    • an email link (optional)
    • a phone link (optional)

  • Blog Page

    • A list of all articles
    • individual article pages
    • LinkedIn
    • GitHub
    • Upwork
    • other professional links (BitBucket, Glitch, StackOverflow, etc.)

Functional Requirements

  • UX/UI

    • Design
      • A clean, modern, responsive user interface with consistently designed components, legible typography and an accessible color pallette.
      • Navigation should be simple and obvious. A header nav with clear links that redirect to each page or scroll to a section. A footer nav with social links and a scroll-to-top button, as well as and necessary legal, copyright, TOS and privacy policy links. Navigation can be consistently accessed from any page.
    • Responsiveness
      • The page should be viewable across all devices, screen sizes and orientations, including: smartphones, tablets and desktops.
    • Accessibility
      • Follow web accessibility guidelines to make the website usable for everyone.

  • Content Management

    • Portfolio Project Data
      • Ability to add, edit, and delete portfolio projects with fields for title, description, images, technologies, and links.
    • Blog Post Creation
      • Ability to create, edit, and publish blog posts with frontmatter options (headers, lists, images).
    • Content Updates
      • Easy content updates through a static website generator or similar tool.

  • Technical Requirements

    • Static Site Generation (SSG)
      • This project will use static website generation for faster loading speeds. Since it is a portfolio website for software development there may also be a use for showcasing server side rendering and other web development features integrated with the website. AstroJS has been chosen as the framework since it can perform SSG and SSR, as well as utilize components built with React, Vue and Svelte.
    • Hosting
      • This website will use Netlify for hosting and DNS, with secure https access. There will be two hosted environments: 1.) a development environment for manual testing of ux/ui on smartphones and other small screens, 2.) a user facing production environment.
    • Deployment
      • The code repository will be stored on GitHub.com. Auto-deployment workflows integrating Netlify and GitHub will be used so that the website builds and deploys to: the development environment whenever new code is merged with the development branch, the production environment whenever new code is merged with the main branch.

Non-Functional Requirements

  • Performance

    • fast loading speeds and times
    • SEO

  • Security

    • HTTPS
    • secure form submissions
    • form honeypots / anti-fishing
    • form validation
    • XSS prevention
    • GitHub branch protection and deployment rules

  • Usability

    • intuitive UI
    • clear Social Links

  • Compatibility

    • cross browser compatibility
    • cross device compatibility and responsiveness

Acceptance Criteria

  • Visual Design

    • visual design aligns with subject’s branding and preferences

  • Functionality

    • all features (portfolio display, blog posts, contact form) function as intended

  • Responsiveness

    • website renders correctly across different devices

  • Performance

    • website loads within acceptable timeframes

Conclusion

  • Key Considerations

    • The key focus is to create a visually appealing, well-structured website that showcases the subject’s work without requiring a complex database or server-side logic
      • Architecture
        • SSG
        • SSR: not required
        • CDN: not required
        • Database: not required
        • Backend: not required
      • Design:
        • Responsiveness: Ensure the website adapts well to different screen sizes (mobile, tablet, desktop) using CSS media queries
        • Accessibility: Follow web accessibility guidelines to make the website usable for everyone
      • SEO Optimization: Implement basic SEO practices (meta descriptions, header tags, sitemap) to improve search engine ranking.

  • Note:

    • This SRS is a high-level overview and may require further refinement based on specific project needs and development technologies.

Technical Design Specification

Front End

  • Astro
    • HTML5
    • CSS3
      • TailwindCSS
    • TypeScript / JavaScript
    • JSON
    • Markdown

Content Management

  • Portfolio Cards (JSON)

    • Portfolio Project Entry
      • project name
      • description of the project
      • specific technologies
      • image
        • thumbnail preview
        • alt description
      • link to project
    • Work or Education History Entry
      • name of the experience
      • description of the experience
      • work or education icon
      • image
        • thumbnail preview
        • alt description
      • link to company or school website
    • Service Offering Entry
      • title for the service offering
      • description of the service offering
    • Technologies Used Entry
      • icon
        • thumbnail preview
        • alt description
      • link to the technology’s website, GitHub or docs (optional)

  • Blog Posts and Blog List Cards (Markdown Frontmatter)

    • Blog Entry
      • post title
      • description for the blog list page
      • publish date
      • hero image
        • thumbnail preview
        • alt description

DevOps

  • Version Control:

    • Git
      • GitHub

  • Hosting

    • Netlify

  • Content Delivery (self contained)

    • .mdx files stored directly in the code repository
    • code pushes to GitHub trigger a new Netlify website build and deploy